Certificate pinning by hiroshihorie · Pull Request #1065 · livekit/client-sdk-flutter

hiroshihorie · 2026-05-05T07:07:35Z

Summary

Adds native certificate pinning support for SDK-owned TLS traffic in the Flutter SDK.

Applies to SDK-owned HTTPS requests and WSS signaling on native platforms
Does not apply to Flutter web, WebRTC media, TURN, or application-owned token endpoints
Validates the peer certificate during TLS connection setup before HTTP or WSS request bytes are sent
Supports SPKI SHA-256 pins, exact leaf certificate bytes, and custom trusted certificate bytes
Adds CertificatePinningException so pinning failures can fail fast and surface clearly

Rule Behavior

Rules are selected by host. Exact hosts, single-label wildcards like *.livekit.cloud, and * are supported. Empty hosts applies a rule to every SDK-owned TLS connection.

All rules that match a host are applied. Within one check type, any configured value may match. Across check types, each configured type must pass.

That means:

Multiple matching SPKI rules form one accepted pin set
primaryPins and backupPins are both accepted
SPKI pins plus exact leaf certificate bytes require both checks to pass
trustedCertificateBytes replaces platform trusted roots for that matching host

Example: SPKI Pins

Use this when possible. It is friendlier to certificate renewal because the pin follows the public key rather than the full leaf certificate.

RoomOptions(
  networkOptions: NetworkOptions(
    certificatePinning: CertificatePinningOptions(
      rules: [
        CertificatePinningRule(
          hosts: ['*.livekit.cloud'],
          primaryPins: ['sha256/current-public-key-pin'],
          backupPins: [
            'sha256/next-public-key-pin-1',
            'sha256/next-public-key-pin-2',
          ],
        ),
      ],
    ),
  ),
)

Example: Exact Leaf Certificate

Use this when the app should trust one exact leaf certificate loaded from assets. Renewing or changing the leaf certificate requires shipping updated certificate bytes unless another configured check also allows the new certificate.

CertificatePinningRule(
  hosts: ['my-project.livekit.cloud'],
  pinnedLeafCertificateBytes: [
    certificate.buffer.asUint8List(),
  ],
)

Example: Custom Trust Store

Use this for the asset-based Flutter pattern where the app ships a leaf, intermediate, or root certificate as trust material.

CertificatePinningRule(
  hosts: ['*.livekit.cloud'],
  trustedCertificateBytes: [
    certificate.buffer.asUint8List(),
  ],
)

Example: Combine Modes

Checks can be combined. This requires the TLS chain to validate against the custom trust store and the peer certificate SPKI to match one configured pin.

CertificatePinningRule(
  hosts: ['*.livekit.cloud'],
  primaryPins: ['sha256/current-public-key-pin'],
  backupPins: [
    'sha256/next-public-key-pin-1',
    'sha256/next-public-key-pin-2',
  ],
  trustedCertificateBytes: [
    certificate.buffer.asUint8List(),
  ],
)

Testing

Added unit coverage for SPKI parsing, real X.509 parsing, wildcard matching, and merged rule semantics
Added native IO tests for HTTPS and WSS failure timing before request bytes are sent
Added native IO tests for exact leaf certificates, trusted leaf certificates, trusted CA certificates, and combined modes

Local verification:

flutter analyze --no-pub
flutter test --no-pub --reporter compact

Copilot

Pull request overview

Adds native certificate pinning support for SDK-owned TLS traffic (internal HTTPS + WSS signaling) by introducing NetworkOptions/pinning rule configuration, enforcing pins/trust stores in the SDK’s IO HttpClient and WebSocket connection path, and documenting usage.

Changes:

Introduces certificate pinning configuration types (NetworkOptions, CertificatePinningOptions, CertificatePinningRule) and CertificatePinningException.
Adds pinning enforcement for SDK-owned HTTP(S) requests and WSS signaling on native platforms (with explicit “unsupported” behavior on Flutter web).
Adds unit + IO tests and README documentation for pinning modes and rule semantics.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/support/certificate_pinning_test.dart	Unit tests for SPKI pin derivation, PEM/DER helpers, host matching, and rule merging semantics.
test/support/certificate_pinning_io_test.dart	Native IO tests validating fail-fast behavior (no HTTP/WSS bytes sent) and trust modes (leaf/trust store/combined).
test/mock/websocket_mock.dart	Extends websocket mock connector to capture `networkOptions` and simulate connect errors.
test/core/certificate_pinning_test.dart	Ensures signaling path passes `networkOptions` through and fast-fails on pinning exceptions.
README.md	Documents certificate pinning scope, rule behavior, and configuration examples.
pubspec.yaml	Adds `asn1lib` and `crypto` dependencies.
pubspec.lock	Locks new direct dependency versions (`asn1lib`, `crypto` now direct).
lib/src/support/websocket/web.dart	Plumbs `networkOptions` and throws on web when pinning is enabled.
lib/src/support/websocket/io.dart	Uses a custom IO `HttpClient` for WSS when pinning is enabled; rethrows pinning exceptions.
lib/src/support/websocket.dart	Extends connector API to accept `networkOptions`.
lib/src/support/region_url_provider.dart	Switches region settings fetch to SDK HTTP client and threads `networkOptions`.
lib/src/support/http_client/web.dart	Web implementation of SDK HTTP client; rejects pinning as unsupported.
lib/src/support/http_client/io.dart	IO implementation of SDK HTTP client with pinning-aware `connectionFactory`.
lib/src/support/http_client.dart	Adds SDK-owned `sdkHttpGet`/`sdkHttpHead` helpers using the platform client.
lib/src/support/certificate_pinning.dart	Implements SPKI pin extraction, PEM/DER utilities, host matching, and validation logic.
lib/src/options.dart	Adds `NetworkOptions` to `RoomOptions` and defines pinning configuration types.
lib/src/exceptions.dart	Adds `CertificatePinningException` for clear surfacing of pinning failures.
lib/src/core/signal_client.dart	Passes `networkOptions` into websocket + validation HTTP request; special-cases pinning failures.
lib/src/core/room.dart	Threads `networkOptions` into region provider and connection preparation HEAD requests.
.changes/add-certificate-pinning	Changelog entry for the new feature.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    if (proxyHost != null || proxyPort != null) {
+      throw UnsupportedError('Certificate pinning through HTTP proxies is not supported');
+    }
+
+    if (!_isTlsScheme(url.scheme)) {
+      return io.Socket.startConnect(url.host, _portFor(url));
+    }


+    final server = await io.SecureServerSocket.bind(
+      io.InternetAddress.loopbackIPv4,
+      0,
+      context,
+    );


…inning

hiroshihorie · 2026-06-23T09:41:35Z

@copilot Does the recent commits address your findings ?

Copilot · 2026-06-23T09:42:45Z

@copilot Does the recent commits address your findings ?

Yes — b28c81e addresses the review findings I raised:

proxy connections are only rejected when TLS pinning applies to the target
the signal client now resets to disconnected on certificate pinning failure
the IO tests now use 127.0.0.1 consistently instead of localhost

The latest runs for that commit also show Build and Changeset Check passing.

Copilot

Pull request overview

Copilot reviewed 21 out of 22 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

lib/src/core/room.dart:239

prepareConnection swallows all exceptions and logs a generic warning without the underlying error. With certificate pinning enabled, this can hide actionable failures (e.g., CertificatePinningException) and makes troubleshooting harder than other nearby code paths that log the error.

          await sdkHttpHead(Uri.parse(toHttpUrl(regionUrl)), networkOptions: roomOptions.networkOptions);
          logger.fine('prepared connection to ${regionUrl}');
        }
      } else {
        await sdkHttpHead(Uri.parse(toHttpUrl(url)), networkOptions: roomOptions.networkOptions);
      }
    } catch (e) {
      logger.warning('could not prepare connection');
    }

+Iterable<List<int>> certificateDerCertificates(CertificateBytes certificate) sync* {
+  switch (certificate.encoding) {
+    case CertificateBytesEncoding.pem:
+      yield* _certificateDerCertificatesFromPem(certificate.bytes);
+    case CertificateBytesEncoding.der:
+      yield certificate.bytes;
+  }
+}



+### Certificate pinning
+
+Certificate pinning is available for native platforms through `RoomOptions.networkOptions`. It applies to SDK-owned WSS signaling and internal HTTPS requests. It does not apply to Flutter web, WebRTC media, TURN, or application-owned token endpoints.


hiroshihorie added 9 commits May 5, 2026 09:00

Add certificate pinning support 1

f7b58fb

Use single-label certificate pin wildcards

abaf4c9

Test SPKI parsing with real certificate

104b196

Document certificate pinning usage

bfee960

Support multiple certificate pinning modes

5800cc8

Use asn1lib for certificate SPKI parsing

ad01fb3

Clarify certificate pinning rule semantics

b7befcd

changes

652143a

Document multiple backup certificate pins

d4340a1

hiroshihorie changed the title ~~Hiroshi/certificate pinning~~ Certificate pinning May 7, 2026

Merge branch 'main' into hiroshi/certificate-pinning

d099834

hiroshihorie marked this pull request as ready for review May 7, 2026 09:38

hiroshihorie requested review from cloudwebrtc and xianshijing-lk as code owners May 7, 2026 09:38

Merge branch 'main' into hiroshi/certificate-pinning

5eff89f

cloudwebrtc approved these changes May 8, 2026

View reviewed changes

hiroshihorie added 2 commits May 27, 2026 19:45

Merge branch 'main' into hiroshi/certificate-pinning

d1aead3

Merge branch 'main' into hiroshi/certificate-pinning

49c114f

hiroshihorie requested a review from Copilot June 23, 2026 06:14

Copilot started reviewing on behalf of hiroshihorie June 23, 2026 06:14 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

hiroshihorie added 2 commits June 23, 2026 17:35

Merge remote-tracking branch 'origin/main' into hiroshi/certificate-p…

c896fbe

…inning

Fix certificate pinning review issues

b28c81e

Copilot started work on behalf of hiroshihorie June 23, 2026 09:41 View session

Copilot finished work on behalf of hiroshihorie June 23, 2026 09:43

hiroshihorie added 3 commits June 26, 2026 14:35

docs: fix certificate pinning room options example

cf98799

Refine certificate byte pinning API

45b686c

Require TLS trust for pinned leaf certificates

e062199

Add certificate asset loading helper

8221770

hiroshihorie requested a review from Copilot June 26, 2026 06:04

Copilot started reviewing on behalf of hiroshihorie June 26, 2026 06:05 View session

Copilot AI reviewed Jun 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Certificate pinning#1065

Certificate pinning#1065
hiroshihorie wants to merge 19 commits into
mainfrom
hiroshi/certificate-pinning

hiroshihorie commented May 5, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

hiroshihorie commented Jun 23, 2026

Uh oh!

Copilot AI commented Jun 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		### Certificate pinning

		Certificate pinning is available for native platforms through `RoomOptions.networkOptions`. It applies to SDK-owned WSS signaling and internal HTTPS requests. It does not apply to Flutter web, WebRTC media, TURN, or application-owned token endpoints.

Uh oh!

Conversation

hiroshihorie commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Rule Behavior

Example: SPKI Pins

Example: Exact Leaf Certificate

Example: Custom Trust Store

Example: Combine Modes

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

hiroshihorie commented Jun 23, 2026

Uh oh!

Copilot AI commented Jun 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hiroshihorie commented May 5, 2026 •

edited

Loading